<HTML><HEAD><TITLE>shelf_create(++ShelfSpec, ?SlotInit, -ShelfHandle)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Non-logical Variables, Arrays, Bags, Shelves and Stores</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>shelf_create(++ShelfSpec, ?SlotInit, -ShelfHandle)</H1>
Create a shelf object which can store data across failures
<DL>
<DT><EM>ShelfSpec</EM></DT>
<DD>A term of the form Name/Arity
</DD>
<DT><EM>SlotInit</EM></DT>
<DD>The value used to initialize the slots (any term)
</DD>
<DT><EM>ShelfHandle</EM></DT>
<DD>A free variable
</DD>
</DL>
<H2>Description</H2>
    	This creates a 'shelf' object which can be used to store
	information across failures.  A typical application is counting
	of solutions, keeping track of the best solution, aggregating
	information across multiple solutions etc.
<P>
	A shelf is an object with multiple slots whose contents survive
	backtracking. The content of each slot can be set and retrieved
	individually, or the whole shelf can be retrieved as a term.
<P>
	Shelves are referred to by handle, not by name, so they make
	it easy to write robust, reentrant code. A shelf disappears when
	the system backtracks over its creation, when the shelf handle
	gets garbage collected, or when it is explicitly destroyed.
<P>
	When using shelf_create/3, ShelfSpec determines the number of
	slots on the shelf, and all slots get initialized identically
	with the value SlotInit.
    
<H3>Modes and Determinism</H3><UL>
<LI>shelf_create(++, ?, -) is det
</UL>
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>ShelfSpec is not fully instantiated
<DT><EM>(5) type error </EM>
<DD>ShelfSpec is fully instantiated but not to a term of the form Atom/Integer
<DT><EM>(5) type error </EM>
<DD>ShelfHandle is not a variable
</DL>
<H2>Examples</H2>
<PRE>
% finding the sum and maximum of data/1 facts:

    data(2).
    data(9).
    data(3).
    data(5).
    data(7).

    sum_and_max(Sum, Max) :-
    	shelf_create(agg/2, 0, Shelf),
	(
	    data(X),
	    shelf_get(Shelf, 1, OldMax),
	    ( X &gt; OldMax -&gt; shelf_set(Shelf, 1, X) ; true ),
	    shelf_get(Shelf, 2, OldSum),
	    NewSum is OldSum + X,
	    shelf_set(Shelf, 2, NewSum),
	    fail
	;
	    shelf_get(Shelf, 0, agg(Max, Sum))
	),
	shelf_abolish(Shelf).
    </PRE>
<H2>See Also</H2>
<A HREF="../../kernel/storage/shelf_create-2.html">shelf_create / 2</A>, <A HREF="../../kernel/storage/shelf_set-3.html">shelf_set / 3</A>, <A HREF="../../kernel/storage/shelf_get-3.html">shelf_get / 3</A>, <A HREF="../../kernel/storage/shelf_abolish-1.html">shelf_abolish / 1</A>
</BODY></HTML>
